@abraca/convert 2.4.0 → 2.5.0

package/README.md

@@ -0,0 +1,28 @@
+# @abraca/convert
+
+The canonical Markdown ↔ Yjs/TipTap round-trip converter — shared by cou-sh, abracadabra-nuxt, and `@abraca/mcp` instead of each vendoring its own copy. **Zero runtime dependencies** (`yjs` peer-only).
+
+## Documentation
+
+Full, code-derived documentation lives in [`docs/`](docs/) — the node/mark spec, the
+universal-meta spec, the conversion API, diff + file-blocks, and a precise
+fidelity/gotchas reference. It is the source of truth (the old `SPEC.md` was untrusted
+and removed).
+
+## API
+
+```ts
+import { populateYDocFromMarkdown, yjsToMarkdown } from "@abraca/convert";
+populateYDocFromMarkdown(doc.getXmlFragment("default"), markdown);
+const { title, markdown } = /* via */ yjsToMarkdown(fragment, label);
+```
+
+Fragment shape: `[documentHeader, documentMeta, ...body]`. Also `populateYDocFromHtml` (needs a global `DOMParser`), `yjsToHtml`, `yjsToPlainText`, structural `diff.ts`, and the FS-sync `file-blocks/` sidecar.
+
+::
+
+> **Attach-before-fill is load-bearing** — `Y.XmlText.insert` on a detached node reverses text (YATA clock 0). Coverage is partial: several spec nodes/marks have no runtime branch, and frontmatter handles a ~13-key subset. See [`docs/4.reference/`](docs/4.reference/1.fidelity-and-gotchas.md).
+
+## License
+
+MIT.

package/dist/abracadabra-convert.cjs

@@ -131,6 +131,23 @@ function parseFrontmatter(markdown) {
 		body
 	};
 }
+function pushNested(out, inner, wrap) {
+	const children = parseInline(inner);
+	if (children.length === 0) {
+		out.push({
+			text: inner,
+			attrs: { ...wrap }
+		});
+		return;
+	}
+	for (const child of children) out.push({
+		text: child.text,
+		attrs: {
+			...child.attrs ?? {},
+			...wrap
+		}
+	});
+}
 function parseInline(text) {
 	const stripped = text.replace(/\{lang="[^"]*"\}/g, "").replace(/:(?!badge|icon|kbd)(\w[\w-]*)\[([^\]]*)\](\{[^}]*\})?/g, "$2").replace(/:(?!badge|icon|kbd)(\w[\w-]*)(\{[^}]*\})/g, "");
 	const tokens = [];
@@ -179,22 +196,10 @@ function parseInline(text) {
 				text: label,
 				attrs: { docLink: { docId } }
 			});
-		} else if (match[10] !== void 0) tokens.push({
-			text: match[10],
-			attrs: { strike: true }
-		});
-		else if (match[11] !== void 0) tokens.push({
-			text: match[11],
-			attrs: { bold: true }
-		});
-		else if (match[12] !== void 0) tokens.push({
-			text: match[12],
-			attrs: { italic: true }
-		});
-		else if (match[13] !== void 0) tokens.push({
-			text: match[13],
-			attrs: { italic: true }
-		});
+		} else if (match[10] !== void 0) pushNested(tokens, match[10], { strike: true });
+		else if (match[11] !== void 0) pushNested(tokens, match[11], { bold: true });
+		else if (match[12] !== void 0) pushNested(tokens, match[12], { italic: true });
+		else if (match[13] !== void 0) pushNested(tokens, match[13], { italic: true });
 		else if (match[14] !== void 0) tokens.push({
 			text: match[14],
 			attrs: { code: true }
@@ -730,11 +735,19 @@ function parseBlocks(markdown) {
 function fillTextInto(el, tokens) {
 	const filtered = tokens.filter((t) => t.text.length > 0);
 	if (!filtered.length) return;
-	const xtNodes = filtered.map(() => new yjs.XmlText());
-	el.insert(0, xtNodes);
+	const children = filtered.map((tok) => {
+		return (tok.attrs?.docLink)?.docId ? new yjs.XmlElement("docLink") : new yjs.XmlText();
+	});
+	el.insert(0, children);
 	filtered.forEach((tok, i) => {
-		if (tok.attrs) xtNodes[i].insert(0, tok.text, tok.attrs);
-		else xtNodes[i].insert(0, tok.text);
+		const node = children[i];
+		if (node instanceof yjs.XmlElement) {
+			const dl = tok.attrs.docLink;
+			node.setAttribute("docId", dl.docId);
+			return;
+		}
+		if (tok.attrs) node.insert(0, tok.text, tok.attrs);
+		else node.insert(0, tok.text);
 	});
 }
 function blockElName(b) {
@@ -1090,6 +1103,15 @@ function populateYDocFromMarkdown(fragment, markdown, fallbackTitle = "Untitled"
 
 //#endregion
 //#region packages/convert/src/yjs-to-markdown.ts
+function isXElem(n) {
+	return !!n && typeof n.nodeName === "string";
+}
+function isXText(n) {
+	return !!n && typeof n.nodeName !== "string" && typeof n.toDelta === "function";
+}
+function localizeFragment(fragment) {
+	return fragment;
+}
 function serializeDelta(delta) {
 	let result = "";
 	for (const op of delta) {
@@ -1150,12 +1172,15 @@ function serializeDelta(delta) {
 }
 function serializeInline(el) {
 	const parts = [];
-	for (const child of el.toArray()) if (child instanceof yjs.XmlText) parts.push(serializeDelta(child.toDelta()));
-	else if (child instanceof yjs.XmlElement) parts.push(serializeInline(child));
+	for (const child of el.toArray()) if (isXText(child)) parts.push(serializeDelta(child.toDelta()));
+	else if (isXElem(child)) if (child.nodeName === "docLink") {
+		const docId = child.getAttribute("docId") ?? "";
+		parts.push(`[[${docId}]]`);
+	} else parts.push(serializeInline(child));
 	return parts.join("");
 }
 function serializeBlock(el, indent = "") {
-	if (el instanceof yjs.XmlText) return serializeDelta(el.toDelta());
+	if (isXText(el)) return serializeDelta(el.toDelta());
 	switch (el.nodeName) {
 		case "documentHeader":
 		case "documentMeta": return "";
@@ -1175,7 +1200,7 @@ function serializeBlock(el, indent = "") {
 		}
 		case "blockquote": {
 			const lines = [];
-			for (const child of el.toArray()) if (child instanceof yjs.XmlElement) {
+			for (const child of el.toArray()) if (isXElem(child)) {
 				const text = serializeBlock(child);
 				for (const line of text.split("\n")) lines.push(`> ${line}`);
 			}
@@ -1236,11 +1261,11 @@ function serializeBlock(el, indent = "") {
 			if (to) props.push(`to="${to}"`);
 			return `::card${props.length ? `{${props.join(" ")}}` : ""}\n${serializeChildren(el)}\n::`;
 		}
-		case "cardGroup": return `::card-group\n${el.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeBlock(c)).join("\n\n")}\n::`;
-		case "codeCollapse": return `::code-collapse\n${el.toArray().filter((c) => c instanceof yjs.XmlElement && c.nodeName === "codeBlock").map((c) => serializeBlock(c)).join("\n\n")}\n::`;
-		case "codeGroup": return `::code-group\n${el.toArray().filter((c) => c instanceof yjs.XmlElement && c.nodeName === "codeBlock").map((c) => serializeBlock(c)).join("\n\n")}\n::`;
+		case "cardGroup": return `::card-group\n${el.toArray().filter((c) => isXElem(c)).map((c) => serializeBlock(c)).join("\n\n")}\n::`;
+		case "codeCollapse": return `::code-collapse\n${el.toArray().filter((c) => isXElem(c) && c.nodeName === "codeBlock").map((c) => serializeBlock(c)).join("\n\n")}\n::`;
+		case "codeGroup": return `::code-group\n${el.toArray().filter((c) => isXElem(c) && c.nodeName === "codeBlock").map((c) => serializeBlock(c)).join("\n\n")}\n::`;
 		case "codePreview": {
-			const children = el.toArray().filter((c) => c instanceof yjs.XmlElement);
+			const children = el.toArray().filter((c) => isXElem(c));
 			const nonCode = children.filter((c) => c.nodeName !== "codeBlock").map((c) => serializeBlock(c)).join("\n\n");
 			const code = children.filter((c) => c.nodeName === "codeBlock").map((c) => serializeBlock(c)).join("\n\n");
 			const parts = [nonCode];
@@ -1258,16 +1283,16 @@ function serializeBlock(el, indent = "") {
 			if (required === true || required === "true") props.push("required=\"true\"");
 			return `::field{${props.join(" ")}}\n${serializeChildren(el)}\n::`;
 		}
-		case "fieldGroup": return `::field-group\n${el.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeBlock(c)).join("\n\n")}\n::`;
+		case "fieldGroup": return `::field-group\n${el.toArray().filter((c) => isXElem(c)).map((c) => serializeBlock(c)).join("\n\n")}\n::`;
 		default: return serializeChildren(el);
 	}
 }
 function serializeChildren(el) {
 	const blocks = [];
-	for (const child of el.toArray()) if (child instanceof yjs.XmlElement) {
+	for (const child of el.toArray()) if (isXElem(child)) {
 		const text = serializeBlock(child);
 		if (text) blocks.push(text);
-	} else if (child instanceof yjs.XmlText) {
+	} else if (isXText(child)) {
 		const text = serializeDelta(child.toDelta());
 		if (text) blocks.push(text);
 	}
@@ -1277,11 +1302,11 @@ function serializeListItems(el, type, indent) {
 	const lines = [];
 	let counter = 1;
 	for (const child of el.toArray()) {
-		if (!(child instanceof yjs.XmlElement) || child.nodeName !== "listItem") continue;
+		if (!isXElem(child) || child.nodeName !== "listItem") continue;
 		const prefix = type === "bullet" ? "- " : `${counter++}. `;
 		const subParts = [];
 		for (const sub of child.toArray()) {
-			if (!(sub instanceof yjs.XmlElement)) continue;
+			if (!isXElem(sub)) continue;
 			if (sub.nodeName === "bulletList") subParts.push(serializeListItems(sub, "bullet", indent + "  "));
 			else if (sub.nodeName === "orderedList") subParts.push(serializeListItems(sub, "ordered", indent + "  "));
 			else subParts.push(serializeInline(sub));
@@ -1297,13 +1322,13 @@ function serializeListItems(el, type, indent) {
 function serializeTaskList(el, indent) {
 	const lines = [];
 	for (const child of el.toArray()) {
-		if (!(child instanceof yjs.XmlElement) || child.nodeName !== "taskItem") continue;
+		if (!isXElem(child) || child.nodeName !== "taskItem") continue;
 		const checked = child.getAttribute("checked");
 		const marker = checked === true || checked === "true" ? "[x]" : "[ ]";
 		let header = "";
 		const nestedParts = [];
 		for (const sub of child.toArray()) {
-			if (!(sub instanceof yjs.XmlElement)) continue;
+			if (!isXElem(sub)) continue;
 			if (sub.nodeName === "paragraph" && header === "") header = serializeInline(sub);
 			else if (sub.nodeName === "bulletList") nestedParts.push(serializeListItems(sub, "bullet", indent + "  "));
 			else if (sub.nodeName === "orderedList") nestedParts.push(serializeListItems(sub, "ordered", indent + "  "));
@@ -1316,16 +1341,16 @@ function serializeTaskList(el, indent) {
 	return lines.join("\n");
 }
 function getCodeBlockText(el) {
-	for (const child of el.toArray()) if (child instanceof yjs.XmlText) return child.toString();
+	for (const child of el.toArray()) if (isXText(child)) return child.toString();
 	return "";
 }
 function serializeTable(el) {
-	const rows = el.toArray().filter((c) => c instanceof yjs.XmlElement);
+	const rows = el.toArray().filter((c) => isXElem(c));
 	if (!rows.length) return "";
 	const serializedRows = [];
 	for (const row of rows) {
-		const cells = row.toArray().filter((c) => c instanceof yjs.XmlElement).map((cell) => {
-			return cell.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeInline(c)).join(" ");
+		const cells = row.toArray().filter((c) => isXElem(c)).map((cell) => {
+			return cell.toArray().filter((c) => isXElem(c)).map((c) => serializeInline(c)).join(" ");
 		});
 		serializedRows.push(cells);
 	}
@@ -1344,7 +1369,7 @@ function serializeTable(el) {
 	].join("\n");
 }
 function serializeSlottedContainer(el, containerName, childName, slotPrefix) {
-	return `::${containerName}\n${el.toArray().filter((c) => c instanceof yjs.XmlElement && c.nodeName === childName).map((item) => {
+	return `::${containerName}\n${el.toArray().filter((c) => isXElem(c) && c.nodeName === childName).map((item) => {
 		const label = item.getAttribute("label") ?? "";
 		const icon = item.getAttribute("icon") ?? "";
 		const props = [];
@@ -1394,7 +1419,7 @@ function escapeYaml(s) {
 	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
 function serializeBlockToHtml(el) {
-	if (el instanceof yjs.XmlText) return serializeDeltaToHtml(el.toDelta());
+	if (isXText(el)) return serializeDeltaToHtml(el.toDelta());
 	const name = el.nodeName;
 	switch (name) {
 		case "documentHeader":
@@ -1408,11 +1433,11 @@ function serializeBlockToHtml(el) {
 		case "orderedList": return `<ol>${serializeListHtml(el)}</ol>`;
 		case "taskList": return `<ul>${serializeTaskListHtml(el)}</ul>`;
 		case "codeBlock": {
-			const lang = el.getAttribute("language") ?? "";
+			const lang = (el.getAttribute("language") ?? "").replace(/[^\w.-]/g, "");
 			const code = escapeHtml(getCodeBlockText(el));
 			return lang ? `<pre><code class="language-${lang}">${code}</code></pre>` : `<pre><code>${code}</code></pre>`;
 		}
-		case "blockquote": return `<blockquote>\n${el.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeBlockToHtml(c)).join("\n")}\n</blockquote>`;
+		case "blockquote": return `<blockquote>\n${el.toArray().filter((c) => isXElem(c)).map((c) => serializeBlockToHtml(c)).join("\n")}\n</blockquote>`;
 		case "table": return serializeTableHtml(el);
 		case "horizontalRule": return "<hr>";
 		case "image": {
@@ -1426,13 +1451,13 @@ function serializeBlockToHtml(el) {
 			if (uploadId) return `<!--fileblock:${uploadId}:${filename}-->`;
 			return `<!-- file: ${filename} -->`;
 		}
-		default: return `<div data-type="${name}">\n${el.toArray().filter((c) => c instanceof yjs.XmlElement || c instanceof yjs.XmlText).map((c) => c instanceof yjs.XmlElement ? serializeBlockToHtml(c) : serializeDeltaToHtml(c.toDelta())).join("\n")}\n</div>`;
+		default: return `<div data-type="${name}">\n${el.toArray().filter((c) => isXElem(c) || isXText(c)).map((c) => isXElem(c) ? serializeBlockToHtml(c) : serializeDeltaToHtml(c.toDelta())).join("\n")}\n</div>`;
 	}
 }
 function serializeInlineHtml(el) {
 	const parts = [];
-	for (const child of el.toArray()) if (child instanceof yjs.XmlText) parts.push(serializeDeltaToHtml(child.toDelta()));
-	else if (child instanceof yjs.XmlElement) parts.push(serializeInlineHtml(child));
+	for (const child of el.toArray()) if (isXText(child)) parts.push(serializeDeltaToHtml(child.toDelta()));
+	else if (isXElem(child)) parts.push(serializeInlineHtml(child));
 	return parts.join("");
 }
 function serializeDeltaToHtml(delta) {
@@ -1451,23 +1476,23 @@ function serializeDeltaToHtml(delta) {
 	return result;
 }
 function serializeListHtml(el) {
-	return el.toArray().filter((c) => c instanceof yjs.XmlElement && c.nodeName === "listItem").map((li) => `<li>${li.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeBlockToHtml(c)).join("")}</li>`).join("\n");
+	return el.toArray().filter((c) => isXElem(c) && c.nodeName === "listItem").map((li) => `<li>${li.toArray().filter((c) => isXElem(c)).map((c) => serializeBlockToHtml(c)).join("")}</li>`).join("\n");
 }
 function serializeTaskListHtml(el) {
-	return el.toArray().filter((c) => c instanceof yjs.XmlElement && c.nodeName === "taskItem").map((ti) => {
+	return el.toArray().filter((c) => isXElem(c) && c.nodeName === "taskItem").map((ti) => {
 		const rawChecked = ti.getAttribute("checked");
 		const checked = rawChecked === true || rawChecked === "true";
-		const text = ti.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeInlineHtml(c)).join("");
+		const text = ti.toArray().filter((c) => isXElem(c)).map((c) => serializeInlineHtml(c)).join("");
 		return `<li><input type="checkbox"${checked ? " checked" : ""} disabled> ${text}</li>`;
 	}).join("\n");
 }
 function serializeTableHtml(el) {
-	const rows = el.toArray().filter((c) => c instanceof yjs.XmlElement);
+	const rows = el.toArray().filter((c) => isXElem(c));
 	if (!rows.length) return "";
 	return `<table>\n${rows.map((row, ri) => {
 		const tag = ri === 0 ? "th" : "td";
-		return `<tr>${row.toArray().filter((c) => c instanceof yjs.XmlElement).map((cell) => {
-			return `<${tag}>${cell.toArray().filter((c) => c instanceof yjs.XmlElement).map((c) => serializeInlineHtml(c)).join("")}</${tag}>`;
+		return `<tr>${row.toArray().filter((c) => isXElem(c)).map((cell) => {
+			return `<${tag}>${cell.toArray().filter((c) => isXElem(c)).map((c) => serializeInlineHtml(c)).join("")}</${tag}>`;
 		}).join("")}</tr>`;
 	}).join("\n")}\n</table>`;
 }
@@ -1475,6 +1500,7 @@ function escapeHtml(s) {
 	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 function yjsToMarkdown(fragment, label, meta, type) {
+	fragment = localizeFragment(fragment);
 	const { text: headerText, source: titleSource } = readDocumentHeader(fragment);
 	const effectiveTitle = headerText || label;
 	const docMeta = readDocumentMeta(fragment);
@@ -1498,7 +1524,7 @@ function readDocumentMeta(fragment) {
 	const meta = {};
 	let type;
 	for (const child of fragment.toArray()) {
-		if (!(child instanceof yjs.XmlElement) || child.nodeName !== "documentMeta") continue;
+		if (!isXElem(child) || child.nodeName !== "documentMeta") continue;
 		const attrs = child.getAttributes();
 		for (const k of Object.keys(attrs)) {
 			const v = attrs[k];
@@ -1518,8 +1544,8 @@ function readDocumentMeta(fragment) {
 }
 function readDocumentHeader(fragment) {
 	for (const child of fragment.toArray()) {
-		if (!(child instanceof yjs.XmlElement) || child.nodeName !== "documentHeader") continue;
-		const text = child.toArray().find((c) => c instanceof yjs.XmlText);
+		if (!isXElem(child) || child.nodeName !== "documentHeader") continue;
+		const text = child.toArray().find((c) => isXText(c));
 		const src = child.getAttribute("titleSource");
 		const source = src === "h1" || src === "frontmatter" ? src : void 0;
 		return {
@@ -1532,7 +1558,7 @@ function readDocumentHeader(fragment) {
 function collectBodyBlocks(fragment) {
 	const out = [];
 	for (const child of fragment.toArray()) {
-		if (!(child instanceof yjs.XmlElement)) continue;
+		if (!isXElem(child)) continue;
 		if (child.nodeName === "documentHeader" || child.nodeName === "documentMeta") continue;
 		out.push(child);
 	}
@@ -1567,9 +1593,10 @@ function isMetaEmpty(meta) {
 * accessibility tooling, search indexing, and snippet previews.
 */
 function yjsToPlainText(fragment) {
+	fragment = localizeFragment(fragment);
 	const out = [];
 	const visit = (node) => {
-		if (node instanceof yjs.XmlText) {
+		if (isXText(node)) {
 			out.push(node.toString());
 			return;
 		}
@@ -1579,17 +1606,18 @@ function yjsToPlainText(fragment) {
 			if (alt) out.push(alt);
 			return;
 		}
-		for (const child of node.toArray()) if (child instanceof yjs.XmlText || child instanceof yjs.XmlElement) visit(child);
+		for (const child of node.toArray()) if (isXText(child) || isXElem(child)) visit(child);
 		if (node.nodeName !== "paragraph" && node.length === 0) return;
 		out.push("\n");
 	};
-	for (const child of fragment.toArray()) if (child instanceof yjs.XmlText || child instanceof yjs.XmlElement) visit(child);
+	for (const child of fragment.toArray()) if (isXText(child) || isXElem(child)) visit(child);
 	return out.join("").replace(/\n+$/, "").replace(/\n{3,}/g, "\n\n");
 }
 function yjsToHtml(fragment, label) {
+	fragment = localizeFragment(fragment);
 	const title = escapeHtml(label);
 	const bodyParts = [];
-	for (const child of fragment.toArray()) if (child instanceof yjs.XmlElement) {
+	for (const child of fragment.toArray()) if (isXElem(child)) {
 		const html = serializeBlockToHtml(child);
 		if (html) bodyParts.push(html);
 	}
@@ -3075,7 +3103,7 @@ function buildReverseLookup(manifest) {
 * e.g. "My Project!" -> "my-project"
 */
 function labelToFilename(label) {
-	return label.toLowerCase().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "untitled";
+	return String(label ?? "").toLowerCase().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "untitled";
 }
 /**
 * Convert a filename back to a label (best-effort).
@@ -3174,7 +3202,8 @@ function simpleHash(str) {
 function getTreeData(treeMap) {
 	const data = {};
 	treeMap.forEach((val, key) => {
-		if (val && typeof val === "object") data[key] = val;
+		const plain = val instanceof yjs.Map || !!val && typeof val === "object" && typeof val.toJSON === "function" && typeof val.get === "function" ? val.toJSON() : val;
+		if (plain && typeof plain === "object") data[key] = plain;
 	});
 	return data;
 }